How To Set Up Password Authentication with Nginx on Ubuntu 14.04

By Justin Ellingwood

When setting up a web server, there are often sections of the site that you wish to restrict access to. Web applications often provide their own authentication and authorization methods, but the web server itself can be used to restrict access if these are inadequate or unavailable.

In this guide, we’ll demonstrate how to password protect assets on an Nginx web server running on Ubuntu 14.04.

To get started, you will need access to an Ubuntu 14.04 server environment. You will need a non-root user with sudo privileges in order to perform administrative tasks. To learn how to create such a user, follow our Ubuntu 14.04 initial server setup guide.

If you haven’t done so already, install Nginx on your machine by typing:

To start out, we need to create the file that will hold our username and password combinations. You can do this by using the OpenSSL utilities that may already be available on your server. Alternatively, you can use the purpose-made htpasswd utility included in the apache2-utils package (Nginx password files use the same format as Apache). Choose the method below that you like best.

If you have OpenSSL installed on your server, you can create a password file with no additional packages. We will create a hidden file called .htpasswd in the /etc/nginx configuration directory to store our username and password combinations.

You can add a username to the file using this command. We are using sammy as our username, but you can use whatever name you’d like:

Next, add an encrypted password entry for the username by typing:

You can repeat this process for additional usernames. You can see how the usernames and encrypted passwords are stored within the file by typing:

While OpenSSL can encrypt passwords for Nginx authentication, many users find it easier to use a purpose-built utility. The htpasswd utility, found in the apache2-utils package, serves this function well.

Install the apache2-utils package on your server by typing:

Now, you have access to the htpasswd command. We can use this to create a password file that Nginx can use to authenticate users. We will create a hidden file for this purpose called .htpasswd within our /etc/nginx configuration directory.

The first time we use this utility, we need to add the -c option to create the specified file. We specify a username (sammy in this example) at the end of the command to create a new entry within the file:

You will be asked to supply and confirm a password for the user.

Leave out the -c argument for any additional users you wish to add:

If we view the contents of the file, we can see the username and the encrypted password for each record:

Now that we have a file with our users and passwords in a format that Nginx can read, we need to configure Nginx to check this file before serving our protected content.

Begin by opening up the server block configuration file that you wish to add a restriction to. For our example, we’ll be using the default server block file installed through Ubuntu’s Nginx package:

Inside, with the comments stripped, the file should look similar to this:

To set up authentication, you need to decide on the context to restrict. Among other choices, Nginx allows you to set restrictions on the server level or inside a specific location. In our example, we’ll restrict the entire document root with a location block, but you can modify this listing to only target a specific directory within the web space:

Within this location block, use the auth_basic directive to turn on authentication and to choose a realm name to be displayed to the user when prompting for credentials. We will use the auth_basic_user_file directive to point Nginx to the password file we created:

Save and close the file when you are finished. Restart Nginx to implement your password policy:

The directory you specified should now be password protected.

To confirm that your content is protected, try to access your restricted content in a web browser. You should be presented with a username and password prompt that looks like this:

If you enter the correct credentials, you will be allowed to access the content. If you enter the wrong credentials or hit “Cancel”, you will see the “Authorization Required” error page:

You should now have everything you need to set up basic authentication for your site. Keep in mind that password protection should be combined with SSL encryption so that your credentials are not sent to the server in plain text. To learn how to create a self-signed SSL certificate to use with Nginx, follow this guide. To learn how to install a commercial certificate, follow this guide.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

author

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

This guide needs updating; You need to chown the .htpasswd file to www-data, otherwise it cannot read it

Is it possible to force the authentication dialog to appear every time the web page, or the web browser for that matter, is closed and opened again?

How about being able to login without a password, e.g. using a client ssh key like ssh does. It’s certainly more convenient, and I often read that ssh auto-login is much safer than using an ssh password.

I followed the guide and am having a similar problem: everything under my.ip.address/ is protected, but when I access a different port, say my.ip.address:1234/, nothing is protected.

I tried jellingwood’s suggestion on Aug 24, 2015, but got the same result.

How can I protect all ports under my.ip.address? It doesn’t seem like the location / location block is catching it.

@jtittle @hansen @jellingwood

i am having a small problem.

i added a password before using openssl, but i forgot it. i know i could add a new user, but i want to edit password for my old user or at least delete old one and create a new one.

also there is one password without any user in my htpasswd file

how can i delete that password without user.

another issue is, i am trying to protect adminer.php. but unfortunately, when i protect that file using http authentication, after giving the password im prompted to download the file. how can i work around this?

this is my server block

You could reduce this article content by 95%. I don’t know why there is a need to explain this for each platform where it isn’t specific to a platform but rather having openssl and nginx installed

Step 1:

Method 1: openssl passwd -apr1 Method 2: htpasswd -c /etc/nginx/.htpasswd sammy

Step 2:

Put it in your nginx file, use the auth_basic directive into the location block.

As others have mentioned, the config (if done incorrectly) can lead to php files being accessible after trying to protect a directory. This is due to the way nginx config prioritises each part of the config.

As most servers have a single php section within their server block, when the request comes in for a php file nginx uses that config, skipping the folder / directory protection section, and serves the resulting html. Bad times.

The correct way to do this is to include a copy of the php section within your password protected section, as follows:

Make a copy of the php section i.e. don’t delete the block from your server config, else you will lose php from the rest of your site.

Credit: http://stackoverflow.com/users/1476414/fisharebest Original Answer: http://stackoverflow.com/questions/4697010/nginx-auth-basic-and-php

You can generate a password without a prompt by piping text into openssl and passing a new flag. For example:

This will echo to stdout. This way you can write a script or something instead of having to use the prompt to type in the password.

If you still wanted to append the output to the /etc/nginx/.htpasswd file, then you would do the following:

I got this working but now I think it would be cool to have a nicely designed login page for my site rather than the default browser dialogue. Is there a way to change the username and password prompt from a browser dialogue to a web form?

Thanks Justin Ellingwood, worked perfectly! Just how I needed it ^^